Chapter 8 - Data Transmission

Web services are used to send transactional data between the host system and Honeywell VoiceCheck. VoiceCheck supports both SOAP and REST web services. These services provide the import and export functionality for the VoiceCheck system.

The services and message formats are described in detail below, and reference XML for the SOAP Web Service Description Language (WSDL) and REST Web Application Description Language (WADL) are provided in the product package. Descriptions of the services were previously viewable by entering http://<host>:<port>/VoiceCheck/services/api/swagger.json into the web browser. This link replaces the previously used link http://<host>:<port>/VoiceCheck/services.

Web Services Message Flow

Configuration and Security

All communications are performed over HTTP or HTTPS, depending on the configuration of VoiceCheck.

For data import, all SOAP web services provided by VoiceCheck require authentication with WS-Security UsernameToken. All REST web services for import require authentication using HTTP basic authentication.

VoiceCheck has an access role, configurable in the user interface, which determines a user's permissions to execute web services. The host system's web service clients must be configured to authenticate with VoiceCheck web services as a user with this role.

For data export, VoiceCheck supports using HTTP basic authentication to access a SOAP or REST web service on the host system. Authentication is optional but if used, it is configured in VoiceCheck, and the password is encrypted and stored in the VoiceCheck database.

VoiceCheck also provides a method to configure the service endpoint URL for services provided by the host system. This endpoint URL is a required setting in the GUI.

There is only one user name and password used to consume all services that the host system exposes for VoiceCheck. Currently, only one service is exposed for VoiceCheck to post assignment results to the host system.

The configuration information (service endpoint, web service client type, user name, and password) is set at the system level in VoiceCheck. These settings can be found on the Administration > System Configuration page. The configuration assumes that one instance of VoiceCheck will connect to a single host system endpoint.

XML Schemas and Namespaces

VoiceCheck declares a namespace for all XML elements used in SOAP and REST services, with the exception of the faultInfo element (see note below). The namespace is:

http://service.web.voicecheck.vocollect.com/

For SOAP services that VoiceCheck provides for data import, find the namespace and schema in the WSDL.

For REST services that VoiceCheck provides for data import, find the namespace and schema in the WADL. Note that for the Create Assignment Web Service, REST clients do not have to qualify the XML with the namespace; however it is highly recommended.

For the REST service that VoiceCheck consumes to post assignment results to a host system, the namespace and schema that the server expects to see in the XML are defined in the example WADL provided in the product package.

The faultInfo element is not defined as part of a namespace. For REST services, VoiceCheck does not qualify the element with a namespace when sending it in an error response to a host system. Similarly, the host system must not qualify a faultInfo element with a namespace in a response to VoiceCheck.

Fault Handling for Assignment Data

REST Fault Handling

On failure, various HTTP status codes can be returned depending on the failure and where the failure occurred during processing. VoiceCheck makes use of the Apache® CXF framework for processing web services requests, and the framework can return errors during its processing such as 406 – Not Acceptable, or 415 – Unsupported Media Type, before the VoiceCheck business logic is reached.

Errors coming from the VoiceCheck business logic only have one of two status codes:

  • 400 – Bad Request: The client has violated a business rule or constraint (usually bad data). Sending the message again without making a change to the content will result in the same error.
  • 500 – Internal Server Error: There was an internal server error while processing the request. Retrying the message MAY result in success.

Also, errors coming from the VoiceCheck business logic include a faultInfo XML element containing additional information about the error that occurred. The properties of the faultInfo element are shown below.

SOAP Fault Handling

SOAP 1.1 faults are returned for all errors. All faults contain a faultcode and faultstring as specified in SOAP 1.1. Two of the core SOAP 1.1 fault codes, Client and Server, are specified for most faults. VoiceCheck generally uses these codes in the manner described in the SOAP 1.1 specification.

There are errors that can occur during authentication that use fault codes specified in WS-Security (Web Services Security). The Java web services APIs and implementations may return other fault codes.

While it is not possible to list every fault code that may occur, there are general rules that can enable consistent handling of faults by web services clients:

  • Fault codes other than Server typically mean that there is no point in automatically resending the message. They are sent when the client has done something wrong prior to the transmission reaching the application logic on the server, such as authentication failures or badly formed messages.
  • When the fault code is Server, if the fault is coming from the application server logic, it will include the SOAP 1.1 fault detail element. The format is specified in the WSDL, but contains the information in the section below.

Fault Info Element

Both REST and SOAP web services include the same error information when a fault comes from the VoiceCheck application server logic.

The host server REST implementation for post assignment results should use this fault info element in order to display the error message in the VoiceCheck GUI; otherwise, the user sees a generic message.

Property Type Definition
errorCode long

Numeric code representing the error.

Valid values:

3000 = Internal server error (request may or may not succeed on retry)

3001 = Bad request (automated request retry is not recommended)
message string Human readable message explaining the error.